Handles `POST /v1/verify/face-match`.

Errors

Returns 400 for undecodable image payloads, 422 when an image cannot be evaluated, and 503 when evidence or verification storage is unavailable. A repeated Idempotency-Key returns 200 with the original verification rather than matching the faces again; see [crate::idempotency].

POST /v1/verify/face-match

Handles `POST /v1/verify/face-match`.

cURL

curl --request POST \
  --url https://qa.esectra.com/v1/verify/face-match \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "candidate_image_base64": "<string>",
  "reference_image_base64": "<string>",
  "subject_id": "<string>"
}
'

200

{
  "decision": "ALLOW",
  "decision_id": "<string>",
  "evidence": [
    {
      "id": "<string>",
      "kind": "IMAGE",
      "location": "<string>",
      "retention_policy": "<string>"
    }
  ],
  "reasons": [
    {
      "code": "<string>",
      "message": "<string>"
    }
  ],
  "review_status": "PENDING",
  "risk_level": "LOW",
  "verification_id": "<string>",
  "review_case_id": "<string>"
}

Authorizations

api_keysession_cookie

Authorization · string · header · required

A tenant API key. Acts for exactly one tenant and cannot conclude a case, because a conclusion records a person.

Body

application/json

Face-match verification request body.

There is deliberately no tenant_id field. It used to be here, and the handler trusted it: any caller could name any tenant, and the route required no credentials at all, so biometrics could be submitted and evidence written against somebody else's account. The tenant now comes from the presented credentials like every other /v1 route, which is the only place it can come from and still mean anything.

candidate_image_base64 · string · required

Base64-encoded candidate image (for example, a live selfie).

reference_image_base64 · string · required

Base64-encoded reference image (for example, an ID document photo).

subject_id · string · required

Subject (platform user) being verified.

Response

200

application/json

A replayed Idempotency-Key; the original verification

Face-match verification response body.

decision · enum<string> · required

Decision outcome.

Available options: ALLOW, WARN, BLOCK, HOLD, REVIEW_REQUIRED, FLAG, BLOCK_RECOMMENDED, SUSPEND, END_STREAM

decision_id · string · required

Decision record identifier.

evidence · object[] · required

References to retained evidence.

Show child attributes

reasons · object[] · required

Explanation reasons.

Show child attributes

review_status · enum<string> · required

Review lifecycle state.

Available options: PENDING, APPROVED, OVERTURNED, NOT_REQUIRED

risk_level · enum<string> · required

Explainable risk level.

Available options: LOW, MEDIUM, HIGH, CRITICAL

verification_id · string · required

Verification attempt identifier.

review_case_id · string | null

Manual-review case, when the decision is borderline.